ITK Programmer's Guide

---

Text conversions

• under Windows, 4D uses the Mac extended ASCII table, so all 4D texts are called as "4D text".
  To convert 4D text into real Windows extended ASCII text, you can use ACI_Pack or some new routine in 4Dv6.

$myText := "<B>é</B>"
$HTML := ITK_Text2HTML($myText) ` returns "&lt;B&gt;&eacute;&lt;/B&gt;"
$HTML := ITK_Text2HTML($myText; 1) ` returns "<B>&eacute;</B>"
 

ITK_HTML2Text
Syntax:	text := ITK_HTML2Text(HTMLText;options)
Description:	Converts HTML text to Mac text. By default, all HTML special characters like "<", ">", "&" are converted unless options is set to 1. All 8bit characters are always converted (ex: é -> &eacute;).
Params:	In/Out Parameter Type     Example or note ->   HTMLText   Text   HTML text to convert     -> options Longint Conversion options 0 = full HTML conversion 1 = reduced HTML conversion ( "&lt;", "&gt;" , "&amp;" and "&quot;" are not converted 2 = extract text (remove HTML tags) <- text Text Converted text
Example:	$myHTMLText := "&lt;B&gt;&eacute;&lt;/B&gt;" $myText := ITK_HTML2Text($myText) ` returns "<B>é</B>" $myText := ITK_HTML2Text($myText; 1) ` returns "&lt;B&gt;é&lt;/B&gt;" $myText := ITK_HTML2Text($myText; 2) ` returns "é" (tags removed)

Back to top

$iso := ITK_Text2ISO("é") ` convert to ISO-8859-1 (Latin-1)

ITK_ISO2Text
Syntax:	text := ITK_ISO2Text(ISOtext;options)
Description:	Convert ISO-8859 text to "4D text" . ISO-8859 defines standard extended ASCII tables for different languages and alphabets (Latin, Cyrillic, etc.). ISO conversion is a table based conversion. This means that the length of the converted text is unchanged.
Params:	In/Out Parameter Type     Example or note ->   ISOtext   Text   ISO text to convert     -> options Longint Conversion options 0 or 1 = use ISO-8852-1 table (Latin-1) 2 = use ISO-8852-2 table (Latin-2) 7 = use ISO-8859-7 table 9 = use ISO-8859-9 table 11 = use ISO-8859-11 table 13 = ISO-8859-13 20 = use ISO-IR-111 table Note: new tables can be added to ITK by modifying ITK's resources. Table names are retrieved through STR#15001. Tables are stored in ITK's resources. <- ISOtext Text Converted text
Example:	$iso := ITK_ISO2Text(ITK_Text2ISO("é")) ` should return "é" !

Back to top

` standard URL translation
$url := ITK_Text2URL("Test 4D+ITK.html")   ` returns "Test+4D%2BITK.html"
 ` form URL translation
$url := ITK_Text2URL("Test 4D+ITK.html";1) ` returns "Test%204D+ITK.html"

` form URL translation
$url := ITK_URL2Text("Test+4D%2BITK.html")   ` returns "Test 4D+ITK.html"
 ` standard URL translation
$url := ITK_URL2Text ("Test+4D%2BITK.html";1) ` returns "Test+4D+ITK.html"

ITK_Text2B64
Syntax:	base64text := ITK_Text2B64(text;options)
Description:	Convert text to Base64. The Base64 conversion is a 8bit to 6bit conversion (3 chars are encoded into 4 chars). The resulting text will be 33% larger than the original.
Params:	In/Out Parameter Type     Example or note ->   text   Text   text to convert Do not pass very long texts as the resulting text will grow by 33%. The limit is around 24000 bytes. -> options Longint Conversion options Currently unused, pass 0 or nothing. <- base64text Text Base64 converted text
Example:	$b64 := ITK_Text2B64("mypassword")

Back to top

ITK_B642Text
Syntax:	text := ITK_B642Text(base64text;options)
Description:	Decodes Base64 text. The Base64 conversion is a 8bit to 6bit conversion (4 chars decoded into 3 chars). The resulting text will be 25% smaller than the original.
Params:	In/Out Parameter Type     Example or note ->   base64text   Text   Base64 text to decode     -> options Longint Conversion options Currently unused, pass 0 or nothing. <- text Text decoded text
Example:	$pass := ITK_B642Text($B64pass)

Back to top

ITK_Text2Quoted
Syntax:	qpText := ITK_Text2Quoted(text;options)
Description:	Encodes some text into "quoted-printable" text. Quoted-printable is a 7bit format that converts 8bit characters into an 6bit encoded representation (ex: "é" -> "=EA"). 7bit characters are not encoded except the equal sign. Quoted-printable also deals will lines wrap and text lines to limit their length (wrapped lines are terminated by a space and an equal sign).
Params:	In/Out Parameter Type     Example or note ->   text   Text   Text to encode     -> options Longint Conversion options 0 = apply ISO 8859-1 encoding before converting to quoted-printable 1 = do not apply ISO encoding <- qpText Text Quoted-Printable encode text.
Example:	$qpISOText := ITK_Text2Quoted($myText) ` apply ISO conversion $qpPlainText := ITK_Text2Quoted($myText;1) ` no ISO conversion

Back to top

ITK_Quoted2Text
Syntax:	text := ITK_Quoted2Text(qpText;options)
Description:	Decodes quoted-printable encoded text. Quoted-printable is a 7bit format that converts 8bit characters into an 6bit encoded representation (ex: "é" -> "=EA"). 7bit characters are not encoded except the equal sign. Quoted-printable also deals will lines wrap and text lines to limit their length (wrapped lines are terminated by a space and an equal sign). This routines restores wrapped lines into their original state.
Params:	In/Out Parameter Type     Example or note ->   qpText   Text   Quoted-Printable text to decode     -> options Longint Conversion options 0 = apply ISO 8859-1 decoding after Quoted-Printable decoding. 1 = do not apply ISO decoding <- text Text decoded text
Example:	$macText := ITK_Quoted2Text($myQPtext) ` apply ISO decoding $isoText := ITK_Quoted2Text($myQPtext;1) ` no ISO decoding

Back to top

ITK_Text2uu
Syntax:	uuText := ITK_Text2uu(text;options)
Description:	Encodes text to uuencode format. The uuencode conversion is a 8bit to 6bit conversion (3 chars are encoded into 4 chars). The resulting text will be 33% larger than the original.
Params:	In/Out Parameter Type     Example or note ->   text   Text   text to encode Do not pass very long texts as the resulting text will grow by 33%. The limit is around 24000 bytes. -> options Longint encoding options Currently unused, pass 0 or nothing. <- uuText Text uuEncoded text
Example:	$uu := ITK_Text2uu("text portion")

ITK_uu2Text
Syntax:	decodedText := ITK_uu2Text(uuText;options)
Description:	Decodes "uu" encoded text. The uuencode conversion is a 8bit to 6bit conversion (3 chars are encoded into 4 chars). The decoded text will be 25% smaller than the encoded version.
Params:	In/Out Parameter Type     Example or note ->   uuText   Text   text to decode     -> options Longint decoding options Currently unused, pass 0 or nothing. <- decodedText Text decoded text
Example:	$t := ITK_uu2Text($uuText)

Picture conversions

ITK_Pict2GIF
Syntax:	gifPicture := ITK_Pict2GIF(picture; flag; gifWidth; gifHeight; transpHoriz; transpVert)
Description:	Compresses a picture in GIF format. An option flag can be use to create an interlaced and/or transparent GIF picture. By default, transparency uses the first pixel (top, left) of the original picture as the transparent colour, but you can also specify any pixel as being the transparent colour. The resulting picture can also be resize.
Warning:	You can store these GIF encoded pictures in 4D records, but do not try to display or do any manipulation on them, 4D doesn't know how to display and manipulate GIF encoded pictures. This can cause 4D to crash.
Params:	In/Out Parameter Type     Example or note -> picture Picture Original 4D picture This picture must be in a classical "PICT" displayable format. Do not pass GIF or JFIF pictures. -> flag Longint Transparency and interlace options 0 = normal GIF 1 = interlaced GIF 2 = transparent GIF 3 = interlaced transparent GIF -> gifWidth Longint Pixel width of resulting GIF Pass 0 to keep the original picture width. -> gifHeight Longint Pixel height of resulting GIF Pass 0 to keep the original picture height -> transpHoriz Longint Horizontal coordinate of transparent pixel     -> transpVert Longint Vertical coordinate of transparent pixel     <- gifPicture Picture Resulting GIF encoded picture May return an empty picture if an error occurred (like memory error or bad original picture).
Example:	$myGIF := ITK_Pict2GIF(myPicture;2;0;0;100;50) ` transparent pixel is (100,50)

Back to top

File conversions

$err := ITK_Mac2Bin("MyHD:MyFolder:Myfile";"MyHD:MyFolder:MyFile.bin") ` MacOS
 $err := ITK_Mac2Bin("C:\MyHD\MyFolder\Myfile";"C:\MyHD\MyFolder\MyFile.bin") ` Windows

ITK_Bin2Mac
Syntax:	error := ITK_Bin2Mac(binPath;macPath)
Description:	Decodes a MacBinary file into an original Mac file.
Params:	In/Out Parameter Type     Example or note -> binPath String Pathname of the MacBinary file to decode Be sure to pass a MacOS formatted pathname under MacOS and a Windows pathname under Windows. -> macPath String Pathname of the resulting file. Be sure to pass a MacOS formatted pathname under MacOS and a Windows pathname under Windows.   <- error Longint OS error code
Example:	$err := ITK_Bin2Mac("MyHD:MyFolder:Myfile.bin";"MyHD:MyFolder:MyFile") ` MacOS  $err := ITK_Bin2Mac ("C:\MyHD\MyFolder\Myfile.bin";"C:\MyHD\MyFolder\MyFile") ` Windows

Back to top

ITK_Mac2Hqx
Syntax:	error := ITK_Mac2Hqx(macPath;binhexPath)
Description:	Encodes a file into BinHex 4.0 format. BinHex 4.0 format allows to store both the data fork and the resource fork of a file with most finders information in a 6bit data fork only file. This is useful under MacOS. BinHex 4.0 is a 6bit file format which can be used to send attachments in email.
Params:	In/Out Parameter Type     Example or note ->   macPath   Text   Pathname of the Mac file to encode Be sure to pass a MacOS formatted pathname under MacOS and a Windows pathname under Windows. -> binhexPath Text Pathname of the resulting BinHex file. Be sure to pass a MacOS formatted pathname under MacOS and a Windows pathname under Windows.   <- error Longint OS error code
Example:	$err := ITK_Mac2Hqx("MyHD:MyFolder:Myfile";"MyHD:MyFolder:MyFile.hqx") ` MacOS  $err := ITK_Mac2Hqx ("C:\MyHD\MyFolder\Myfile";"C:\MyHD\MyFolder\MyFile.hqx") ` Windows

Back to top

ITK_Hqx2Mac
Syntax:	error := ITK_Hqx2Mac(binhexPath;macPath)
Description:	Decodes a BinHex 4.0 file into an original Mac file.
Params:	In/Out Parameter Type     Example or note -> binhexPath String Pathname of the MacBinary file to decode Be sure to pass a MacOS formatted pathname under MacOS and a Windows pathname under Windows. -> macPath String Pathname of the resulting file. Be sure to pass a MacOS formatted pathname under MacOS and a Windows pathname under Windows.   <- error Longint OS error code
Example:	$err := ITK_Hqx2Mac("MyHD:MyFolder:Myfile.hqx";"MyHD:MyFolder:MyFile") ` MacOS  $err := ITK_Hqx2Mac ("C:\MyHD\MyFolder\Myfile.hqx";"C:\MyHD\MyFolder\MyFile") ` Windows

Back to top

ITK_Mac2uu
Syntax:	error := ITK_Mac2uu(macPath; uuPath)
Description:	Encodes a file into uuencode format. uuencode is a standard Unix 6bit encoding file format. uuencode does not deal with resource forks and finder information.
Params:	In/Out Parameter Type     Example or note -> macPath String Pathname of the original file Be sure to pass a MacOS formatted pathname under MacOS and a Windows pathname under Windows. -> uuPath String Pathname of the resulting file. Be sure to pass a MacOS formatted pathname under MacOS and a Windows pathname under Windows.   <- error Longint OS error code
Example:	$err := ITK_Mac2uu("MyHD:MyFolder:Myfile";"MyHD:MyFolder:MyFile.uu") ` MacOS  $err := ITK_Mac2uu("C:\MyHD\MyFolder\Myfile";"C:\MyHD\MyFolder\MyFile.uu") ` Windows

Back to top

ITK_uu2Mac
Syntax:	error := ITK_uu2Mac(uuPath;macPath)
Description:	Decodes a "uuencoded" file into an original Mac file.
Params:	In/Out Parameter Type     Example or note -> uuPath String Pathname of the MacBinary file to decode Be sure to pass a MacOS formatted pathname under MacOS and a Windows pathname under Windows. -> macPath String Pathname of the resulting file. Be sure to pass a MacOS formatted pathname under MacOS and a Windows pathname under Windows.   <- error Longint OS error code
Example:	$err := ITK_uu2Mac("MyHD:MyFolder:Myfile.uu";"MyHD:MyFolder:MyFile") ` MacOS  $err := ITK_uu2Mac("C:\MyHD\MyFolder\Myfile.uu";"C:\MyHD\MyFolder\MyFile") ` Windows

Back to top

Date conversions

ITK_RFC2Secs
Syntax:	gmtValue := ITK_RFC2Secs(rfcString)
Description:	Converts an RFC#822 or RFC#1123 formatted date and time string (example: Fri, 28-Jul-1995 22:50:10 +0100) into a GMT date/time value.
Note:	ITK_RFC2Secs and ITK_Date2Secs are always returning a GMT based value, so you can compare them directly. Y2K Compliance: note that if the rfcString passed is formatted according to RFC#822 (which uses only 2 digits for the year), this routine will not be Y2K compliant. Be sure to pass RFC#1123 formatted string which are using 4 digits for the year.
Params:	In/Out Parameter Type     Example or note -> rfcString String RFC formatted date/time string (see example) This string must be formatted according to RFC#822 or RFC#1123. <- gmtValue Longint GMT Date/Time value.
Example:	To convert an RFC date/time string into the corresponding GMT RFC date/time string use theString := ITK_Secs2RFC(ITK_RFC2Secs(theString);1) To compare two RFC date/time strings, converts them into GMT date/time values, ex: If (ITK_RFC2Secs(myRFCdate1)>ITK_RFC2Secs(myRFCdate2)) ...

Back to top

ITK_Secs2RFC
Syntax:	rfcString := ITK_Secs2RFC(gmtValue;timeZoneFlag)
Description:	Converts a GMT date/time value into an RFC#822 or RFC#1123 formatted date and time string (example: Fri, 28-Jul-1995 22:50:10 +0100). You can specify if the resulting RFC string must be in GMT time zone or local time zone (according to your computer time zone settings).
Note:	ITK_RFC2Secs and ITK_Date2Secs are always returning a GMT based value, so you can compare them directly. Y2K Compliance: This routine is Y2K compliant.
Params:	In/Out Parameter Type     Example or note -> gmtValue Longint GMT date/time value As returned by ITK_RFC2Secs or ITK_Date2Secs. -> timeZoneFlag Longint flag to indicate in which time zone the result must be provided. 0 = local Time Zone 1 = GMT Time Zone <- rfcString String RFC#1123 formatted string "Fri, 28-Jul-1995 22:50:10 +0100"
Example:	To convert an RFC date/time string into the corresponding GMT RFC date/time string use theString := ITK_Secs2RFC(ITK_RFC2Secs(theString);1) To get the current date and time in GMT time zone: theString := ITK_Secs2RFC(ITK_Date2Secs(Current Date; CurrentTime;1);1)

Back to top

ITK_Date2Secs
Syntax:	gmtValue := ITK_Date2Secs(date;time;timeZoneFlag)
Description:	Converts a date and time (4D formats) into an GMT date/time value. You can specify if the given date and time are in local time zone or GMT.
Warning:	If you pass a local date and time (like Current Date and Current Time), be sure to specify local time zone in the timeZoneFlag, otherwise, the resulting gmtValue will not be correct according to your local time zone and GMT time zone. See examples below. Y2K Compliance: This routine is Y2K compliant.
Params:	In/Out Parameter Type     Example or note -> date Date Date to convert This date is in 4D standard format. -> time Time Time to convert This time is in 4D standard format. -> timeZoneFlag Longint indicates in which time zone the date and time are given. 0 = GMT time zone 1 = local time zone <- gmtValue Longint GMT date/time value
Example:	$secs := ITK_Date2Secs(Current date; Current time; 1) ` local time (in local time zone) $secs := ITK_Date2Secs(!12/25/96!;Ý00:00:00Ý;0) ` Christmas date, GMT time

Back to top

ITK_Secs2Date
Syntax:	ITK_Secs2Date(gmtValue;date;time;timeZoneFlag)
Description:	Converts GMT date/time value into a date and time (4D formats). You can specify if the resulting date and time must be returned in local time zone or GMT. Y2K Compliance: This routine is Y2K compliant.
Params:	In/Out Parameter Type     Example or note -> gmtValue Longint GMT date/time value As returned by ITK_RFC2Secs or ITK_Date2Secs. <- date Date Corresponding date This date is in 4D standard format. <- time Time Corresponding time This time is in 4D standard format. -> timeZoneFlag Longint Indicates in which time zone the date and time should be returned. 0 = local time zone 1 = GMT time zone
Example:	` Get date/Time in 4 hours $dt := ITK_Date2Secs(Current Date; Current Time;1) $dt := $dt + (4*60*60) ` add 4 hours ITK_Secs2Date($dt;$nextDate;$nextTime;0) `local Time Zone

Back to top